Text Properties and Instance Swap Properties are important Figma Component Property types used to make reusable components flexible, editable, and easier to manage. Text Properties allow designers to change text content directly from an instance, while Instance Swap Properties allow designers to replace a nested component with another suitable component without detaching the main instance.
These properties are especially useful when building professional design systems containing buttons, cards, navigation items, list items, forms, notifications, menus, product cards, dashboards, and other reusable UI components.
JustAcademy Figma Training | Register for Figma Course Demo
A Text Property is a Figma Component Property that identifies text content inside a component as editable. When the component is used as an instance, users can change the connected text from the Properties section in the right sidebar or directly on the canvas.
For example, a reusable button can have a Text Property called Label. Each button instance can then display different text such as Login, Submit, Download, or Continue.
Text Property = A component property that allows editable text content to be changed in an instance.
Text Property
↓
Editable Text Content
↓
Component Instance
↓
Change Text
↓
New Content Appears
An Instance Swap Property is a component property that allows a nested component instance inside a main component to be replaced with another suitable component.
For example, a button may contain a nested icon instance. An Instance Swap Property can allow designers to change the icon from Search to Download, Edit, Delete, Share, or another approved icon without manually restructuring the component.
Instance Swap Property = A component property that allows a nested component instance to be replaced with another component instance.
Instance Swap Property
↓
Nested Component
↓
Property Control
↓
Choose Replacement
↓
New Component Appears
| Feature | Text Property | Instance Swap Property |
|---|---|---|
| Main Purpose | Edit text content | Replace nested component |
| Value Type | Text/String | Component Instance |
| Example | Button Label | Button Icon |
| Control | Text field | Component selection control |
| Common Use | Labels, titles, descriptions | Icons, avatars, actions, illustrations |
| Design System Benefit | Editable content | Controlled component replacement |
Text Properties make reusable components easier to customize. Instead of opening layers and manually selecting text layers, designers can expose only the text that is intended to be changed.
Instance Swap Properties provide controlled flexibility. Designers can replace nested components while preserving the main component structure and design-system rules.
Consider a reusable button component.
Button
└── Label
Create a Text Property:
Property:
Label
Default Value:
Submit
Instances can then use different values.
Button 1 → Submit
Button 2 → Login
Button 3 → Continue
Button 4 → Download
Consider a button with an icon.
Button
├── Icon Instance
└── Label
Create an Instance Swap Property:
Property:
Icon
Default:
Search Icon
The designer can then replace the icon with another suitable component.
Search
Download
Share
Edit
Delete
When a Text Property is applied to a main component, instances can edit the exposed text while remaining connected to the main component.
Main Component
↓
Text Property
↓
Create Instance
↓
Edit Text
↓
Instance remains connected
An Instance Swap Property exposes a nested instance as a controlled replacement point.
Main Component
↓
Nested Component
↓
Instance Swap Property
↓
Create Instance
↓
Choose Replacement
↓
Nested Component Changes
To create a Text Property, select a main component or component set and define which text content should be editable.
Suppose you are creating a reusable button.
Button
└── Text Layer
Label.Button.Property:
Label
Default:
Button
After creating the component instance, the Text Property appears in the component Properties section of the right sidebar.
Button Instance
Properties
────────────
Label: Submit
The designer can change the value:
Label: LoginThe button text updates while the instance remains connected to the main component.
Navigation Item
├── Icon
└── Label
Create:
Text Property:
Label
Possible values:
Home
Dashboard
Settings
Profile
Reports
Card
├── Title
├── Description
└── CTA
Possible Text Properties:
Title
Description
CTA Label
This allows one card component to support multiple content scenarios.
Product Card
├── Product Name
├── Price
├── Description
└── Button
Possible properties:
Product Name
Price
Description
Button Label
Notification
├── Title
└── Message
Possible Text Properties:
Title
Message
For example:
Title:
Success
Message:
Your profile has been updated.
Input Field
├── Label
├── Placeholder
└── Helper Text
Possible Text Properties:
Label
Placeholder
Helper Text
Modal
├── Title
├── Description
├── Primary Button
└── Secondary Button
Possible Text Properties:
Title
Description
Primary Label
Secondary Label
Empty State
├── Title
├── Description
└── Action
Possible Text Properties:
Title
Description
Action Label
Text Property names should clearly communicate what content they control.
LabelTitleDescriptionMessagePlaceholderHelper TextCTA LabelProduct NameText 1Content AStringProperty 1A default value provides meaningful starting content for the component.
Property:
Label
Default:
Continue
Choose a default value that communicates the intended usage of the component.
Text Properties separate component structure from component content. The designer maintains the component layout while allowing users to change the information displayed inside it.
Structure
+
Editable Content
=
Reusable Component
Text Properties work particularly well with Auto Layout. When the text changes, the layout can respond according to the component's Auto Layout settings.
Short Text
[ Save ]
Long Text
[ Save Changes ]
Auto Layout
↓
Adjusts component size
Always test short and long text values to ensure the component remains visually correct.
Responsive components often need different amounts of text. Text Properties make it easier to test different content lengths while maintaining the component structure.
Desktop:
Learn More About Our Services
Mobile:
Learn More
Text Properties can work alongside text variables. Where appropriate, a Text Property can use a string variable as its value, helping connect reusable component content with a variable-based design system.
String Variable:
buttonLabel = "Continue"
Text Property:
Label
Result:
Continue
Text Properties are primarily intended to expose editable text content. When text requires special formatting or complex rich-text treatment, designers should test the behavior carefully and make content changes directly on the canvas when necessary.
For example, if a text layer contains special formatting such as list styling, changing the text through the property control may not preserve every formatting detail in the same way as editing the text layer directly.
An Instance Swap Property is created for a nested component instance that should be replaceable.
Consider a button containing an icon instance.
Button
├── Icon Instance
└── Label
Icon.Preferred Instances allow component creators to curate a list of recommended components that users can select when using an Instance Swap Property.
This is especially useful when a library contains many similar components but only a limited set should be used in a particular component.
Icon Property
↓
Preferred Instances
↓
Search
Download
Share
Edit
Delete
Button
├── Icon
└── Label
Instance Swap:
Icon
Preferred instances:
Search
Download
Share
Edit
The designer can select an appropriate icon without manually rebuilding the nested component structure.
Profile Card
├── Avatar Instance
├── Name
└── Role
Create:
Instance Swap:
Avatar
The avatar can then be replaced with another approved avatar component.
Empty State
├── Illustration
├── Title
└── Description
Property:
IllustrationPossible replacement instances:
No Results
No Data
Error
Success
Welcome
Card
├── Content
└── Action Instance
An Instance Swap Property can allow the action component to change while maintaining the card structure.
Instance Swap Properties provide controlled flexibility. Instead of allowing designers to freely restructure a component, the component creator defines which nested instance can be replaced.
Flexible
↓
But Controlled
↓
Design-System Consistency
| Manual Text Override | Text Property |
|---|---|
| Designer may need to locate the text layer | Text is exposed as a clear property |
| Less discoverable | Easy to find in Properties |
| Can create uncertainty about editable content | Clearly communicates intended editable content |
| Less centralized | Centralized component control |
| Manual Instance Swap | Instance Swap Property |
|---|---|
| Select nested instance manually | Use the exposed property |
| May require entering component hierarchy | Replacement is available through Properties |
| Less guided | Can provide preferred instances |
| More effort for users | Faster component configuration |
| Text Property | Instance Swap Property |
|---|---|
| Changes text | Changes nested component |
| Uses text values | Uses component instances |
| Example: Button Label | Example: Button Icon |
| Controlled through text input | Controlled through component selection |
| Useful for content | Useful for interchangeable components |
Professional components often use both properties together.
Button
├── Icon Instance
└── Label
Properties:
Icon → Instance Swap
Label → Text Property
This creates a flexible component where both the content and visual icon can be changed.
Button
├── Icon Instance
└── Label
Properties:
Show icon → Boolean
Icon → Instance Swap
Label → Text
Possible instance:
Icon:
Download
Label:
Download File
A highly reusable component can combine multiple property types.
Button
├── Icon
└── Label
Properties:
Show icon → Boolean
Icon → Instance Swap
Label → Text
This allows designers to control whether the icon appears, which icon is used, and what text is displayed.
Variants can manage component states while Text and Instance Swap Properties manage content and nested components.
Variants:
State = Default / Hover / Pressed / Disabled
Text:
Label
Instance Swap:
Icon
This separation keeps the component architecture easier to understand.
A list item is an excellent example of multiple component properties working together.
List Item
├── Leading Icon
├── Label
├── Metadata
└── Trailing Component
Properties:
Leading Icon → Instance Swap
Label → Text
Metadata → Text
Trailing → Instance Swap
Label:
Settings
Metadata:
Updated today
Leading Icon:
Settings Icon
Trailing:
Chevron Icon
The same list item component can be reused across different screens with different content and nested components.
Navigation Item
├── Icon
├── Label
└── Badge
Properties:
Icon → Instance Swap
Label → Text
A Boolean Property can additionally control the visibility of an optional badge.
Product Card
├── Product Image
├── Product Name
├── Price
├── Rating
└── Action
Possible properties:
Product Image → Instance Swap
Product Name → Text
Price → Text
Action → Instance Swap
User Card
├── Avatar
├── Name
├── Role
└── Action
Properties:
Avatar → Instance Swap
Name → Text
Role → Text
Action → Instance Swap
Notification
├── Icon
├── Title
├── Message
└── Action
Properties:
Icon → Instance Swap
Title → Text
Message → Text
Action → Instance Swap
Form Field
├── Label
├── Input
├── Status Icon
└── Helper Text
Possible properties:
Label → Text
Placeholder → Text
Status Icon → Instance Swap
Helper Text → Text
Modal
├── Icon
├── Title
├── Description
├── Primary Action
└── Secondary Action
Possible properties:
Icon → Instance Swap
Title → Text
Description → Text
Primary Action → Instance Swap
Secondary Action → Instance Swap
Empty State
├── Illustration
├── Title
├── Description
└── Action
Properties:
Illustration → Instance Swap
Title → Text
Description → Text
Action → Instance Swap
Alert
├── Icon
├── Title
├── Message
└── Action
Properties:
Icon → Instance Swap
Title → Text
Message → Text
Action → Instance Swap
Good:
Title
Description
Label
Placeholder
CTA Label
Avoid:
Text 1
Text 2
Content A
String
Preferred Instances should represent components that are appropriate for the context.
Property:
Icon
Preferred:
Search
Download
Share
Edit
Do not add every available component if only a small curated group is appropriate.
Text Properties help designers reuse a consistent component structure while changing only the content. This prevents users from creating separate components simply because the text is different.
One Component
↓
Many Text Values
↓
Consistent Structure
Instance Swap Properties help designers replace nested components while preserving the intended component structure. This makes them particularly useful for icons, avatars, illustrations, actions, and other interchangeable assets.
Both property types work effectively with Auto Layout when the component is structured correctly.
Text Changes
↓
Content Width Changes
↓
Auto Layout Adjusts
Instance Changes
↓
Nested Component Changes
↓
Layout Responds
Always test different text lengths and replacement components.
Variants and component properties have different responsibilities.
| Feature | Best Use |
|---|---|
| Variant | Distinct states, sizes, styles, or structural variations |
| Text Property | Editable content |
| Instance Swap | Replaceable nested components |
| Boolean Property | Show or hide optional layers |
These properties can work together in a single component.
Button
├── Icon
└── Label
Properties:
Show icon → Boolean
Icon → Instance Swap
Label → Text
This gives designers three useful controls without requiring multiple duplicate components.
Select Main Component
↓
Select Text Layer
↓
Create Text Property
↓
Name Property
↓
Set Default Value
↓
Create Instance
↓
Edit Text
↓
Test Content Length
↓
Reuse Component
Select Main Component
↓
Select Nested Instance
↓
Create Instance Swap Property
↓
Name Property
↓
Set Default Instance
↓
Add Preferred Instances
↓
Create Instance
↓
Choose Replacement
↓
Test Layout
↓
Reuse Component
Create Component
↓
Identify Editable Text
↓
Identify Replaceable Components
↓
Create Text Properties
↓
Create Instance Swap Properties
↓
Add Preferred Instances
↓
Configure Auto Layout
↓
Create Component Instance
↓
Test Text Changes
↓
Test Component Swaps
↓
Check Responsive Behavior
↓
Document Component
↓
Publish to Design System
Not every text layer needs to be exposed as a Text Property. Decorative or fixed text can remain part of the component structure.
Fixed:
"Success"
Editable:
"Your payment was completed successfully."
Expose only the content that users are expected to change.
A property called Text 1 does not tell the user what it controls.
Bad:
Text 1
Text 2
Better:
Title
Description
Button Label
Instance Swap should not be used simply because content changes. If the requirement is only to change text, use a Text Property.
Change words
→ Text Property
Change component
→ Instance Swap Property
A Text Property cannot replace a nested icon, avatar, illustration, or action component. Use Instance Swap for interchangeable component instances.
Preferred Instances should be curated. Adding every available component can make the replacement menu difficult to use.
Always test Text Properties with short, medium, and long content.
Short:
Save
Medium:
Save Changes
Long:
Save Changes and Continue
Check wrapping, resizing, alignment, and Auto Layout behavior.
Different nested components may have different dimensions. When using Instance Swap, test replacement components to ensure that the layout remains correct.
If the requirement is to represent distinct component states such as Default, Hover, Pressed, or Disabled, Variants are generally more appropriate.
Different State
→ Variant
Different Nested Component
→ Instance Swap
Text Properties provide a clear indication of which content is intended to be configurable. This can help designers and developers understand the reusable component structure.
Component:
Button
Label:
Editable
Icon:
Swappable
Instance Swap Properties communicate that a nested component is intentionally replaceable. This can make design-system documentation easier to understand.
Icon:
Swap allowed
Preferred:
Search
Download
Share
When reusable components are published as part of a shared library, clearly defined Text and Instance Swap Properties make components easier for other designers to configure correctly.
Complex components should have documentation explaining which properties can be changed and how they should be used.
Button
Label:
Change to match the action.
Icon:
Choose an approved icon.
State:
Use variants for interaction states.
Editable text should remain meaningful and accessible in the final product.
When swapping icons or other visual components, ensure that the replacement component is appropriate for the intended meaning and accessibility requirements.
| Requirement | Use |
|---|---|
| Change button text | Text Property |
| Change card title | Text Property |
| Change description | Text Property |
| Change icon | Instance Swap Property |
| Change avatar | Instance Swap Property |
| Change illustration | Instance Swap Property |
| Show or hide an element | Boolean Property |
| Change button state | Variant Property |
Create a button that supports editable text and replaceable icons.
Button
├── Icon Instance
└── Label
Properties:
Show icon → Boolean
Icon → Instance Swap
Label → Text
Example:
Show icon = True
Icon = Download
Label = Download File
Create a list item with editable label and metadata and replaceable leading and trailing components.
List Item
├── Leading Instance
├── Label
├── Metadata
└── Trailing Instance
Properties:
Leading → Instance Swap
Label → Text
Metadata → Text
Trailing → Instance Swap
Product Card
├── Product Image
├── Product Name
├── Price
├── Rating
└── Action
Properties:
Image → Instance Swap
Product Name → Text
Price → Text
Action → Instance Swap
User Card
├── Avatar
├── Name
├── Role
└── Action
Properties:
Avatar → Instance Swap
Name → Text
Role → Text
Action → Instance Swap
Notification
├── Icon
├── Title
├── Message
└── Action
Properties:
Icon → Instance Swap
Title → Text
Message → Text
Action → Instance Swap
| Test | Expected Result |
|---|---|
| Change short text | Text updates correctly |
| Change medium text | Layout remains correct |
| Change long text | Wrapping and resizing work correctly |
| Reset text | Default value returns correctly |
| Use multiple instances | Each instance can have appropriate content |
| Check Auto Layout | Spacing and alignment remain correct |
| Test | Expected Result |
|---|---|
| Swap default component | Replacement appears correctly |
| Choose preferred component | Selected component replaces original |
| Swap multiple times | Each replacement works correctly |
| Check component dimensions | Layout remains correct |
| Check Auto Layout | Spacing adjusts correctly |
| Check instance connection | Main component relationship remains intact |
Component
│
├── Content
│ ├── Title → Text
│ └── Description → Text
│
├── Visuals
│ ├── Icon → Instance Swap
│ └── Avatar → Instance Swap
│
├── Optional Elements
│ └── Badge → Boolean
│
└── States
└── Default / Hover / Pressed / Disabled → Variants
This architecture separates content, interchangeable components, optional elements, and component states.
A Text Property is a component property that allows designated text content inside a component to be edited through an instance.
An Instance Swap Property allows a nested component instance to be replaced with another suitable component instance.
They appear as editable text controls in the component Properties section of the right sidebar when working with an instance.
They appear as component-selection controls in the component Properties section of the right sidebar.
A common use is exposing a button label, card title, description, placeholder, or notification message for editing.
A common use is allowing an icon, avatar, illustration, or nested action component to be replaced.
Preferred Instances are curated component choices that help users quickly select appropriate replacements for an Instance Swap Property.
Yes. A component can use Text Properties for editable content and Instance Swap Properties for replaceable nested components.
Text Property changes content, while Variants represent distinct component variations or states.
Instance Swap replaces a nested component, while Boolean controls whether an associated layer is visible or hidden.
Text Property
↓
Editable Text
↓
Title / Label / Description
↓
Flexible Content
Instance Swap Property
↓
Replace Nested Component
↓
Icon / Avatar / Illustration
↓
Controlled Flexibility
Button
├── Icon Instance
└── Label
Properties:
Show icon
→ Boolean
Icon
→ Instance Swap
Label
→ Text
State
→ Variant
Example instance:
State:
Default
Show icon:
True
Icon:
Download
Label:
Download File
Another instance can use:
State:
Default
Show icon:
True
Icon:
Share
Label:
Share File
The same reusable component supports different content, icons, and states while maintaining the underlying design-system structure.
| Question | Recommended Property |
|---|---|
| Does the user need to change words? | Text Property |
| Does the user need to replace an icon? | Instance Swap Property |
| Does the user need to replace an avatar? | Instance Swap Property |
| Does the user need to show or hide an element? | Boolean Property |
| Does the user need a different component state? | Variant Property |
| Does the user need to insert flexible content? | Slot Property |
Text Properties and Instance Swap Properties are powerful tools for creating flexible and scalable Figma components. Text Properties allow designers to expose meaningful text content for editing, while Instance Swap Properties allow nested component instances to be replaced without manually restructuring the main component.
Text Properties are ideal for labels, titles, descriptions, messages, placeholders, and other editable content. Instance Swap Properties are ideal for icons, avatars, illustrations, actions, and other interchangeable components. Preferred Instances can further improve usability by providing a curated list of approved replacement options.
When combined with Boolean Properties, Variants, Auto Layout, Variables, and a well-organized design system, Text and Instance Swap Properties help create components that are flexible for users while still maintaining strong design-system consistency and control.
